View AN664_4635863.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

rev. 0.2 3/12 copyright ? 2012 by silicon laboratories AN664 AN664 p recision 32? cmsis and hal u ser ? s g uide 1. introduction cmsis is the cortex microcontroller software interfac e standard, and the hardware access layer (hal) is a defined part of this standard. the hal provides an access layer for the sim3xxxx device registers. the functions and macros are non-blocking and simple; they cannot return error codes, so they are de signed to never fail. the hal is designed to replace the individual bit field accesses of the module with a function name that describes the action the bit is controlling. note: hal functions and macros are not designed to be thread-s afe. these routines do not disable interrupts during non- monotonic register modifications. the hal is one layer above the hardware and is the only c ode that accesses the regist ers directly. more complex firmware systems like a real time operating system (rto s) or code example call th e hal and cmsis routines. figure 1 shows the precision32? firmware layer block diagram. figure 1. firmware layer block diagram 2. relevant documentation precision32 application notes are listed on the following website: www.s ilabs.com/32bit-appnotes. ?? an668: precision32? software developm ent kit (sdk) code examples overview ?? an670: getting started wit h the silicon labs pr ecision32? appbuilder ?? an672: precision32? si32library overview ?? an673: precision32? software development kit overview ?? an675: precision32? de velopment suite overview callback cmsis rtos si32library application cmsis coresupport from arm hal from silicon labs code examples hardware
AN664 2 rev. 0.2 3. peripheral memory organization each peripheral exists as a set of registers in memory. most peripherals start at 0x1000 address blocks in the peripheral memory area starting at address 0x4000_0000. t he base pointer of a perip heral points to the starting address of the peripheral, and each regist er is an offset from the base address. in the case of the usart0 module, the base pointer is si32_usart_0, and it is assigned an address of 0x4000_0000, since it?s the first peripheral in the peripheral memory area. the registers each take 16 bytes (0x10) of memory: a word each for the register and the set, clr, and msk addresses. these addresses are reserved for registers that do not implement them. figure 2 shows the usart0 registers as they appear in memory. figure 2. usart0 registers in memory sim3xxxx address space config config_set config_clr si32_usart_0 0x4000_0000 0x4000_0004 0x4000_0008 0x4000_000c 0x4000_0010 mode mode_set mode_clr flowcn flowcn_set flowcn_clr 0x4000_0014 0x4000_0018 0x4000_001c 0x4000_0020 0x4000_0024 0x4000_0028 0x4000_002c
AN664 rev. 0.2 3 4. hal organization the hal is organized based on the sim3xxxx peripheral modules. modules of the same type and revision are exactly the same, so these modules share the same generi c description. the individual instances of the modules then instantiate their own copies of the generic descrip tion. for example, the hal implements a usart (module) a (revision) type. this type is then instantiated mult iple times for usart0 and usart1, which have their own base pointers. each generic module has a *_registers.h file that contains a module structur e comprised of register structures and bit fields properly aligned in memory. the *_type.h file contains the hal interface for the module, and the *_type.c contains the hal implementation. so me modules will also have a *_suppor t.h file that contains helpful enumeration definitions. finally, a device header file named for the device (e.g., sim3u1xx.h) contains base pointer and interrupt vector instantiations for each module on a device. figure 3 displays a block diagram sho wing the relationship of the hal files. figure 3. hal block diagram interrupt vectors base pointers sim3u1xx.h module register and bit definitions registers.h function prototypes and macros type.h functions type.c enumerated type definitions support.h
AN664 4 rev. 0.2 4.1. usart0 hal example the sim3u1xx.h device file contains the usart0 inte rrupt vector (usart0_irqn) and base pointer information (si32_usart_0). the si32_usart_a_registers.h file contai ns the module structure, which includes structures of bit fields for each register. the si32_usart_a_type.h and type.c files contain routines that access each of these bits. figure 4 displays a block diagram showing the rela tionship of the hal files for the usart0 module. figure 4. example usart hal block diagram firmware can call the usart0 select tx parity routine using the base pointer defined in si3mu1xx.h and the function implemented in si32_usart_a_type.c: si32_usart_a_select_tx_parity(si32_usart_0, parity); interrupt vector: usart0_irqn base pointer: si32_usart_0 sim3u1xx.h usart0 void _si32_usart_a_select_tx_parity( si32_usart_a_type * basepointer, uint32_t parity) { assert(parity < 4); // parity < 2^2 //{{ basepointer->config_clr = si32_usart_a_config_tparmd_mask; basepointer->config_set = parity << si32_usart_a_config_tparmd_shift; //}} } si32_usart_a_type.c void _si32_usart_a_select_tx_parity( si32_usart_a_type * basepointer, uint32_t parity); si32_usart_a_type.h config.tparmd #define si32_usart_a_config_tparmd_mask 0x00600000 #define si32_usart_a_config_tparmd_shift 21 // odd parity. #define si32_usart_a_config_tparmd_odd_value 0 #define si32_usart_a_config_tparmd_odd_u32 \ (si32_usart_a_config_tparmd_odd_value << si32_usart_a_config_tparmd_shift) ... si32_usart_a_registers.h
AN664 rev. 0.2 5 table 1 shows an example set of registers for the usart0 module. figure 5 illustrates the resulting usar t module structure in registers.h. figure 5. example usart module structure table 1. example usart registers register name title address (all access) set (+0x4) clr(+0x8) msk (+0xc) usart0 registers usart0_config module configuration 0x4000_0000 y y usart0_mode module mode select 0x4000_0010 y y usart0_flowcn flow control 0x4000_0020 y y usart0_control module control 0x4000_0030 y y usart0_ipdelay inter-packet delay 0x4000_0040 usart0_baudrate transmit and receive baud rate 0x4000_0050 usart0_fifocn fifo control 0x4000_0060 y y usart0_data fifo input/output data 0x4000_0070
AN664 6 rev. 0.2 each of the registers has a correspondi ng structure that defines the bit fields within that register. in addition, registers that implement the clear and set addresses have 32-bit variables defined at the appropriate addresses. figure 6 shows the config register structure, which is declared as a part of the usart module structure. figure 6. example usart config register structure this config register structure has the tparmd 2-bit fi eld that controls the transmit parity. the u32 value declared at the bottom of the structure is a union with the bit fields and is an entity that firmware can use to access the entire register at one time. the hal type.c functions and macros can access the entire usart0 config register: si32_usart_0->config.u32 = config; the hal can also read or write the tparmd field in the usart0 config register: parity = si32_usart_0->config.tparmd; si32_usart_0->config_set = parity << si32_usart_a_config_tparmd_shift; finally, the hal can clear the tparmd field: si32_usart_0->config_clr = si32_usart_a_config_tparmd_mask;
AN664 rev. 0.2 7 2. detailed hal overview the hal for each module consists of *_registers.h, *_ty pe.h, and *_type. c file. some modules will have an additional *_support.h file. this section discus ses the role of each of these files in detail. note: all definitions, functions, and macros in the silicon labs hal start with a si32_ shield to prevent any potential conflicts with other code in the system. 2.1. registers header file (registers.h) the *_registers.h file creates a memory map of the module ?s registers and bits. in addition, this file declares detailed definitions to manipulate each bit or field. 2.1.1. registers each of the module?s registers are defined as: struct si32_peripheral_r_register_struct { union { struct { volatile uint32_t bitfield0: 4; volatile uint32_t bitfield1: 12; volatile uint8_t bitfield2; volatile uint32_t bitfield3: 4; uint32_t reserved0: 4; }; volatile uint32_t u32; }; }; in this definition, peripheral is the generic name of the peripheral (usart, for example), r is the revision (a, b, etc.), and register is the name of the register. the size of the bitfields in a register structure must add up to 32 bits. any 8- or 16-bit bitfields aligned on 8-bit boundaries are not defined as bitfields but as uint8_t or uint16_t . unused bitfield regions are defined as reserved# .
AN664 8 rev. 0.2 fifo registers are not defined using any bitfields. if byte accesses are not allowed, the register structure does not include a uint8_t definition. the same applies to half-word accesses and the uint16_t definition. all fifos are accessed from the least significant byte, so there is no ex plicit access provided for the upper three bytes or the upper half-word. struct si32_peripheral_r_register_struct { union { volatile uint8_t u8; volatile uint16_t u16; volatile uint32_t u32; }; }; 2.1.2. bitfields each of the bitfields of a module has several defines in the *_registers.h file. these defines all have the form si32_module_revision_register_bitfield_definetype . the definetype is: ?? mask: a bit mask for the position of the bit or field in the register. ?? shift: a left-shift value for the position of the bit or field in the register. ?? enumeration_value or enumeration_u32: these enumerations define every valid value of the bit or field. the enumerations also include a u32 version that the hal routines can write to entire register using the defined shift value. for example, with the iprdy bit in the epcontr ol register (bit 0) of the usbep module: #define si32_usbep_a_epcontrol_iprdyi_mask 0x00000001 #define si32_usbep_a_epcontrol_iprdyi_shift 0 // the packet has been sent or there is an open fifo slot. #define si32_usbep_a_epcontrol_iprdyi_not_set_value 0 #define si32_usbep_a_epcontrol_iprdyi_not_set_u32 \ (si32_usbep_a_epcontrol_iprdyi_not_set_value << si32_usbep_a_epcontrol_iprdyi_shift) // a packet is loaded in the fifo. #define si32_usbep_a_epcontrol_iprdyi_set_value 1 #define si32_usbep_a_epcontrol_iprdyi_set_u32 \ (si32_usbep_a_epcontrol_iprdyi_set_value << si32_usbep_a_epcontrol_iprdyi_shift) the not_set and set definitions are the enumerations for this bit. the value definitions set the value of each valid bit value, and the u32 definitions are the appropriate write value fo r the bit when writing to entire register.
AN664 rev. 0.2 9 2.1.2.1. using the mask definition the hal uses mask definitions to clear or set bitfields in registers that support clear and set addresses. in these cases, the address can be set equal to the mask directly to manipulate the bitfield. for example: void _si32_usart_a_disable_rx_start_bit(si32_usart_a_type * basepointer) { //{{ basepointer->config_clr = si32_usart_a_config_rstrten_mask; //}} } 2.1.2.2. using the shift definition the hal uses the shift definition when a field value is passed to a ro utine. this allows the calling code to pass in a raw value, and the hal can handle the actual placem ent of the bitfield in the register. for example: void _si32_usart_a_select_rx_stop_bits(si32_usart_a_type * basepointer, si32_usart_a_stop_bits_enum_type bits) { assert(bits < 4); // bits < 2^2 //{{ basepointer->config_clr = si32_usart_a_config_rstpmd_mask; basepointer->config_set = bits << si32_usart_a_config_rstpmd_shift; //}} } 2.1.2.3. using the enumeration definitions the hal uses the u32 enumeration definitions for the clear and set addresses or when accessing the entire register. the hal does not use the value definitions themselves whenever possible, since accessing a single bitfield in a register is inefficient. for example: void _si32_usart_a_enable_rx_error_interrupts(si32_usart_a_type * basepointer) { //{{ basepointer->control_set = si32_usart_a_control_rerien_enabled_u32; //}} }
AN664 10 rev. 0.2 2.1.3. modules a module structure at the end of each *_registers.h file aggregates all of the peripherals?s registers and spaces them from the peripheral base pointer address: typedef struct si32_peripheral_r_struct { struct si32_peripheral_r_regname1_struct register1; uint32 register1_set; uint32 register1_clr; uint32_t reserved0; struct si32_peripheral_r_register2_struct register2; uint32_t reserved1; uint32_t reserved2; uint32_t reserved3; } si32_peripheral_r_type; the struct is assumed to start at offset 0x0 from the peripheral?s base pointer. in this example, register1 is at address 0x0 and supports clear and set addresses, so register1_set is located at 0x04 and register1_clr is located at 0x08. there is no mask address defined for this register, so the corresponding address 0x0c is simply marked as reserved# . register2 has no set, clear, or mask addresse s, so these offsets are also defined as reserved# . this struct is never allocated as a variable; it is simply used as offsets from a base pointer.
AN664 rev. 0.2 11 2.2. type header (type.h) and code (type.c) files the *_type.h file creates the interface definition of the mo dule. this file includes f unction prototypes and macro definitions for each of the hal routines. including this file in a source file means that file now has access to all of the hal routines for a module. the *_type.c file is the implementation of the module hal functions. this file includes all of the function declarations for the prototypes in the *_type.h file. each of the routines starts with the si32_ shield and the module name. the descriptive name of the function then follows. for example, the ro utine to set the iprdyi bi t in the usbep module is: void _si32_usbep_a_set_in_packet_ready(si32_usbep_a_type * basepointer); 2.2.1. function naming the function names for the hal follow a set of guidelines to make them consistent and predictable across modules: ?? names are in lower case , including acronyms: read_nss_pin . ?? do not use abbreviations, with one exception being tx for transmit and rx for receive. ?? separate words us ing underscores. ?? use enable_module and disable_module for bits that control the whole module. ?? use reset_module for bits that reset the whole module. ?? use select for functions that are selecting an item that is mutually exclusive from other options. this is common with settings that involve multiple bitfields. ?? use enter_mode_description_mode and exit_mode_description_mode for non-mutually exclusive items, and all enter_mode functions must have an exit_mode counterpart. for example, to enter the irda mode in the usart module: enter_rx_irda_mode . ?? use set , get , and clear for bits and registers. for example: set_parity_even , get_status , clear_carry_flag . ?? use numerical value for numbers. for example: set_fifo_threshold_1 , set_fifo_threshold_2 . ?? use read and write when manipulating data or pins. for example: read_fifo , write_fifo , read_nss_pin . ?? use start and stop for things that run, lik e oscillators and timers. ?? use enable , disable , ? is enabled ?, ? is pending ?, and clear for interrupts. for example: enable_overrun_interrupt , disable_overrun_interrupt , is_overrun_interrupt_pending , and clear_overrun_interrupt . ?? use has for events that have flags but do not cause interrupts. for example: has_buffer_overflow_occurred . ?? for debug bits, use the enable_stall_in_debug_mode and disable_stall_in_debug_mode routine names. ?? functions referring to the peripheral should always use the module keyword.
AN664 12 rev. 0.2 2.2.2. required functions each module must have the following functions: ?? initialize ?? enable_module whenever a corresponding bit exists ?? disable_module whenever a corresponding bit exists ?? reset_module whenever a corresponding bit exists ?? a write_ function for each register ?? a read_ function for each register ?? enable__interrupt for each interrupt ?? disable__interrupt for each interrupt ?? is__interrupt_enabled for each interrupt ?? is__interrupt_pending for each interrupt ?? clear__interrupt for each interrupt the initialize function takes all writable registers as parameters and copies them into the registers. this function is knowledgeable about order, whenever order matters. the write register functions take the register value as a pa rameter and copies it into the register. the read register functions return the va lue of the register. 2.2.3. return an d parameter types return types must be one of the following: ?? void ?? bool ?? uint32_t ?? uint16_t ?? uint8_t ?? enumeration type defined for the module in *_support.h when returning a bool value, the functions explicitly typecast the return value as a bool. parameters must be one of the following: ?? uint32_t ?? uint16_t ?? uint8_t ?? bool ?? enumeration type defined for the module in *_support.h the functions use these types for all parameters used to ca rry values that are smaller than 32 bits but are passed wide for efficiency: ?? wide8_t: value can be converted to signed 8-bit number without loss of precision ?? uwide8_t: value can be converted to unsigned 8-bit number without loss of precision ?? wide16_t: value can be converted to signed 16-bit number without loss of precision ?? uwide_16_t: value can be converted to unsigned 16-bit number without loss of precision these types indicate to the calling code that, while the parameter is passed wide, the actual value will be stored narrow in the indicated storage format.
AN664 rev. 0.2 13 2.2.4. function implementation guidelines functions do not block or return erro r codes. this serves several purposes: 1. this eliminates the need for the hal to validate parameters, beyond debug bounds assertions. 2. this eliminates the need for the calling code to validate the return codes. if a function could not be safely implemen ted without polling, such as enabling an external oscillator, then it is not a hal function. this function ality is left to a higher level of firmware, like the si32library or appbuilder. functions are not allowed to allocate memory locally or use global variables . as a result, the functions will not be able to maintain state separa te from what is maintained in the registers themselves. functions are as efficient as possible. for set or clear operations, functions use the set or clear addresses, where applicable. read-modify-write operations are used only when absolutely necessary when clearing a field before setting it to a new value causes an issue, like undesired pin transitions. all functions have four or fewer parameters whenev er possible, including the base pointer to the module. 2.3. optional suppo rt files (support.h) the *_support.h files are optional for a module and share the same basic template as *_type.h files. these files contain helpful enumerations for modules and any other support code necessary. the format for these enumerations is: typedef enum si32_peripheral_struct { si32_peripheral_enumname1 = 0, si32_peripheral_enumname2 = 1, ... } si32_peripheral_enum_type; the enumerations provide set values for a function parameter to eliminate the chance of using an invalid value and to make code more readable. for example: typedef enum si32_rstsrc_struct { si32_rstsrc_pin_reset = 0, si32_rstsrc_power_on_reset = 1, si32_rstsrc_vdd_monitor = 2, ... } si32_rstsrc_enum_type; the get_last_reset_source routine can then return a value of this enumeration type: si32_rstsrc_enum_type _si32_rstsrc_a_get_last_reset_source( si32_rstsrc_a_type * basepointer); firmware can then decode the return value of th is routine using the enumeration values defined in si32_rstsrc_a_support.h to create readable and less error-prone code.
AN664 14 rev. 0.2 2.4. hal startup code the si32hal startup implementation differs from the cmsis recommendation in order to support multiple tool chains. each individual application ha s explicit control over all of its me mory model, including the stack, heap, ram, retention ram, and emif. the symbo ls used to define the base and size of these memory areas is available for use by the application without duplication. the hal uses tool chain-specif ic linker control files in the si32-x.y\si32hal\device directory to specify these ranges. these files are: ?? gcc/precision32: linker_devicefamily_p32.ld ?? arm: linker_devicefamily_arm.sct ?? iar: linker_devicefamily_iar.icf the code examples also provide basic linker control files th at are sufficient for many applications. for cases where these linker files are not sufficient, the application developer should use applicat ion-specific linker files. 3. performance the hal implements both macros and func tions for most routines. this allows firmware la yers that call the hal to choose between the faster performance of macros or the sma ller footprint of functions. for the routines that do not have an implemented macro, a macro still exists, bu t it just calls the function. the functions and macros have the same parameters and names, but functions have an underscore prefix. for example, the function for settin g the usart transmit parity is: _si32_usart_a_select_tx_parity(si32_usart_0, parity); the macro for the same routine is: si32_usart_a_select_tx_parity(si32_usart_0, parity); 4. revisions each version of the hal sits in a separate folder. the path of these is c:\silabs\32bit\si32\si32-x.y , where x is the primary hal version and y is the secondary hal version. each time a new version of the hal is installed, it will leave all previous versions to eliminate the chance of a new install breaking a working firmware project. in addition, any deprecated functions will remain a part of the hal. these functions will either remain unchanged or call the new version to prevent the need to modify firmware when migrating to a newer version of the hal. 5. code examples each version of the hal includes stand-alone code exampl es for the device modules that use the macro routines by default. these examples can be found in c:\silabs\32bit\si32-x.y\examples after installing the precision32 ide. 6. the hal and appbuilder the silicon labs appbuilder program uses hal macros when configurin g peripherals. the appbuilder project options can select between different versions of the hal.
AN664 rev. 0.2 15 7. detailed documentation the detailed silicon labs cmsis docum entation can be found in the si32hal wi ndows help file (si32hal.chm). the documentation includes the cortex-m3 co re register definitions, core functi on interface, and core instruction interface, as well as the sim3xxxx hal. the si32hal file shown in figure 7 is installed in c:\silabs\32bit\si32-x.y\documentation after installing the precision32 software package from www.silabs.com/32bit-software. figure 7. silicon labs hal and cmsis documentation
AN664 16 rev. 0.2 d ocument c hange l ist revision 0.1 to revision 0.2 ?? updated figure 1. ?? updated the name of the hal help file to si32hal.chm. ?? added section 2.
AN664 rev. 0.2 17 n otes :
AN664 18 rev. 0.2 c ontact i nformation silicon laboratories inc. 400 west cesar chavez austin, tx 78701 tel: 1+(512) 416-8500 fax: 1+(512) 416-9669 toll free: 1+(877) 444-3032 please visit the silicon labs technical support web page: https://www.silabs.com/support/pages/contacttechnicalsupport.aspx and register to submit a technical support request. silicon laboratories and silicon labs are trademarks of silicon laboratories inc. other products or brandnames mentioned herein are trademarks or registered trademarks of their respective holders. the information in this document is believed to be accurate in all respects at the time of publication but is subject to change without notice. silicon laboratories assumes no responsibility for errors and omissions, and disclaims responsib ility for any consequences resu lting from the use of information included herein. a dditionally, silicon laboratorie s assumes no responsibility for the functioning of und escribed features or parameters. silicon laboratories reserves the right to make changes without further notice . silicon laboratories makes no wa rranty, rep- resentation or guarantee regarding the suitability of its products for any particular purpose, nor does silicon laboratories as sume any liability arising out of the application or use of any product or circuit, and s pecifically disclaims any an d all liability, including wi thout limitation conse- quential or incidental damages. silicon laborat ories products are not designed, intended, or authorized for use in applications intended to support or sustain life, or for any other application in which the failure of the silicon laboratories product could create a s ituation where per- sonal injury or death may occur. should buyer purchase or us e silicon laboratories products for any such unintended or unauthor ized ap- plication, buyer shall indemnify and hold silicon laboratories harmless against all claims and damages.

▲Up To Search▲

Price & Availability of AN664

	To Download AN664 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .